YOLO 错误码说明 - YoloErrorCodes

概述

以下 YOLO 接口在失败时返回负数，其绝对值即为错误码，与 GetLastError() 返回值一致：

• 加载类：YoloLoadModel / YoloLoadModelEx / YoloLoadModelMemory / YoloLoadModelMemoryEx
• 管理类：YoloReleaseModel / YoloSetModelConfig / YoloSetModelConfigByKey / YoloWarmup / YoloClearError
• 加解密类：YoloEncryptModel / YoloEncryptModelEx / YoloDecryptModel / YoloDecryptModelEx

成功时：

• 加载类：返回 大于 0 的模型句柄
• 操作类：返回 1

推理类接口（YoloDetect* / YoloClassify* / …）仍返回 JSON 字符串；失败时 JSON 含 "success":false，同时会写入 GetLastError()，便于统一排查。

失败时建议同时调用：

• GetLastError()：获取错误码（正整数，如 8006）
• GetLastErrorString()：获取中文说明（用完后 FreeStringPtr 释放）
• YoloGetLastError()：获取后端详细错误文本/JSON（GPU 设备列表等）

long handle = ola.YoloLoadModelEx("models/yolo11n.onnx", "", "person|car", 1, 0, -1);
if (handle <= 0) {
    int err = GetLastError();                 // 例如 8006
    int code = handle < 0 ? (int)(-handle) : err;
    char* msg = (char*)GetLastErrorString();
    char* yoloMsg = (char*)ola.YoloGetLastError();
    // 根据 code 排查，见下表
    FreeStringPtr((int64_t)msg);
    FreeStringPtr((int64_t)yoloMsg);
} else {
    // handle 可用于 Detect / Classify / ...
    ola.YoloReleaseModel(handle);
}

重要：判断加载是否成功请用 handle > 0，不要再用 handle != 0（失败时返回负错误码）。

通用错误（10xx）

返回值	GetLastError	说明	排查建议
-1001	1001	权限不足 / 未登录	Login/Reg；FeatureList 须含 Yolos / YOLO 特性
-1003	1003	参数无效	instance 无效等

YOLO 错误（80xx）

返回值	GetLastError	说明	排查建议
-8001	8001	YOLO 参数无效	空路径、非法内存地址/长度、类型越界；NCNN 缺 .param 等
-8002	8002	模型/标签/图片文件不存在	检查路径、SetPath 工作目录、文件是否可读
-8003	8003	非欧拉加密包或包格式无效	明文请用 YoloLoadModelEx；加密包用 YoloLoadModel
-8004	8004	加密包密码错误或为空	检查 password
-8005	8005	加密包解密失败	密码、包损坏、头信息不完整
-8006	8006	后端加载模型失败	权重与 inferenceType/modelType 是否匹配；看 YoloGetLastError
-8007	8007	无效的 YOLO 模型句柄	是否已 Release；句柄是否来自本实例
-8008	8008	模型加密打包或写出失败	写出路径权限、磁盘空间；savePath 是否可写
-8009	8009	模型配置失败	JSON 字段名是否合法；句柄是否有效
-8010	8010	推理设备不可用 / GPU 索引越界	先用 YoloListDevices 取合法 DeviceIndex；TensorRT/ONNX 须选 NVIDIA；可改 -1 CPU（TensorRT 不支持 CPU）
-8011	8011	图像无效或读取失败	imagePtr / 文件路径
-8012	8012	屏幕区域截图失败	绑定窗口、区域坐标、截图后端
-8013	8013	当前构建未启用 YOLO	使用带 YOLO 的发布包
-8099	8099	YOLO 操作内部异常	联系支持并提供日志
-9999	9999	未知错误	查看日志 / YoloGetLastError

加解密常见排查（YoloEncryptModel / Ex）

现象	常见返回值	说明
ONNX 能加密、NCNN 失败	-8002 / -8001	NCNN（modelType=2）需可读的 .bin + .param；相对路径相对 SetPath 工作目录
names / labels 找不到	-8002	namesLabel 为文件路径时同样走 WorkPath；内联 `
加密写出失败	-8008	savePath 目录无写权限或磁盘不足；目录不存在时一般会自动创建父目录
参数为空	-8001	modelPath / password / savePath 不可为空

判断成功：加解密 / 配置类接口成功返回 1；失败返回负错误码（如 -8002），不要再用 ret == 0 判断失败。

int ret = ola.YoloEncryptModel(
    "/yolo/best.ncnn.bin", "/yolo/best.ncnn.param", "/yolo/class_name.names",
    "123456", 2, 0, "/models/dxr.olam");
if (ret != 1) {
    int code = ret < 0 ? -ret : GetLastError(); // 例如 8002
    char* msg = (char*)GetLastErrorString();
    // 根据 code / msg 排查
    FreeStringPtr((int64_t)msg);
}

相关接口

接口	说明
YoloLoadModelEx	加载明文模型
YoloLoadModel	加载加密包
YoloEncryptModel	加密到文件
YoloEncryptModelEx	加密到内存
YoloGetLastError	后端详情（亦可用插件 GetLastErrorString）
GetLastError	读取错误码
YOLO 模块总览	流水线与选型